﻿//-----------------------------------------------------------------------------------------
// <copyright file="Vibrate.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System.Runtime.InteropServices;

    /// <summary>
    /// The vibrate capabilities supported by the phone.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct VibrateCapabilities
    {
        /// <summary>
        /// Periodic vibrate support. TRUE if supported, FALSE otherwise.
        /// </summary>
        public bool VibratePeriodicIsSupported;

        /// <summary>
        /// The maximum on time value allowed, in milliseconds. Applicable to both one-time and periodic vibrate.
        /// </summary>
        public uint MaxOnTime;

        /// <summary>
        /// The maximum off time value allowed, in milliseconds. Applicable only to periodic vibrate.
        /// </summary>
        public uint MaxOffTime;

        /// <summary>
        /// The maximum duration allowed, in milliseconds. Applicable only to periodic vibrate.
        /// </summary>
        public uint MaxDuration;
    }

    /// <summary>
    /// A periodic vibrate sequence.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct VibratePeriodicAttributes
    {
        /// <summary>
        /// Desired vibrate time during one period.
        /// </summary>
        /// <remarks>
        /// Valid values range from 1 to \c maxOnTime.
        /// </remarks>
        public uint OnTime;

        /// <summary>
        /// Desired non-vibrate time during one period.
        /// </summary>
        /// <remarks>
        /// Valid values range from 1 to \c maxOffTime.
        /// </remarks>
        public uint OffTime;

        /// <summary>
        /// The total play time, in milliseconds. The vibrate cycle (which is \c onTime plus \c offTime) will be repeated for the duration. 
        /// </summary>
        /// <remarks>
        /// In the case that \c onTime plus \c offTime is set greater than the duration, the duration is changed to \c onTime plus \c offTime.
        /// </remarks>
        public uint Duration;
    }

    /// <summary>
    /// Samsung Vibrate API.
    /// </summary>
    /// <remarks>
    /// The Vibrate API enables you to make the phone vibrate.
    /// </remarks>
    public class Vibrate
    {
        /// <summary>
        /// Gets the vibrate capabilities supported by the phone.
        /// </summary>
        /// <param name="capabilities">A pointer to an <see cref="T:SamsungMobileSDKNET.VibrateCapabilities"/> struct that receives the vibrate capabilities.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the capabilities parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if vibrate not supported
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiVibrateGetCapabilities")]
        public static extern ResultCode GetCapabilities(
            [Out] out VibrateCapabilities capabilities);

        /// <summary>
        /// Vibrates the phone once. This function returns immediately without waiting for the vibration to complete.
        /// </summary>
        /// <param name="onTime">Vibrate time, in milliseconds. Allowed range of values is 1 to maxOnTime.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if onTime is not within allowed range
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if one-time vibrate is not supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiVibrateOnce")]
        public static extern ResultCode Once(
            [In] uint onTime);

        /// <summary>
        /// Vibrates the phone perodically, according to the attributes given. This function returns immediately without waiting for the periodic vibration to complete.
        /// </summary>
        /// <param name="attributes">Periodic vibrate sequence desired.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if attribites is NULL (or) values of members of attributes are not within their valid range
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if periodic vibrate is not supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiVibratePeriodic")]
        public static extern ResultCode Periodic(
            [In] VibratePeriodicAttributes[] attributes);

        /// <summary>
        /// Halts the current phone vibration.
        /// </summary>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if vibrate is not supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiVibrateStop")]
        public static extern ResultCode Stop();
    }
}
